<?xml version="1.0" ?>
<!--
Copyright 2004-2005 The Apache Software Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<document>

	<properties>
		<author email="nicko at apache dot org">Nicko Cadell</author>
		<title>Contributing to log4net Development</title>
	</properties>

	<meta name="keywords" content="contributing to log4net development, contributing log4net, log4net svn, log4net cvs, log4net" />

	<body>
		<section id="main" name="Contributing to log4net Development">
		
			<sectionMenu name="Contents" />

<!--
			<p>
				blah blah mailing list, svn, issues, blah
			</p>
-->
		
			<section id="mlist" name="Developer Mailing List">
				<p>
					All discussion relating to log4net development takes place on this list. All SVN checkin 
					notifications are also copied to this list.
				</p>
			
				<section id="mlist-archive" name="Mailing List Archives">
					<p>
						You can browse the mailing list archives at the following locations:
					</p>
					
					<ul>
						<li><a href="http://mail-archives.eu.apache.org/mod_mbox/logging-log4net-dev/">mod_mbox</a></li>
						<li><a href="http://nagoya.apache.org/eyebrowse/SummarizeList?listId=214">eyebrowse</a></li>
						<li><a href="http://marc.theaimsgroup.com/?l=log4net-dev&amp;r=1&amp;w=2">MARC</a></li>
						<li><a href="http://sourceforge.net/mailarchive/forum.php?forum=log4net-devel">Old Mailing List at sourceforge</a></li>
					</ul>
				</section>

				<section id="mlist-subscribe" name="Subscribe">
					<p>
						Subscribe to either the list or to the digest list:
					</p>
					
					<ul>
						<li>
							<p>
								To subscribe to this list send an e-mail to <br />
								<a href="mailto:log4net-dev-subscribe@logging.apache.org">log4net-dev-subscribe@logging.apache.org</a>.
							</p>
						</li>
							
						<li>
							<p>
								To subscribe to the digest list sent an e-mail to <br />
								<a href="mailto:log4net-dev-digest-subscribe@logging.apache.org">log4net-dev-digest-subscribe@logging.apache.org</a>.
							</p>
						</li>
					</ul>
				</section>

				<section id="mlist-unsubscribe" name="Unsubscribe">
					<p>
						To unsubscribe send an email to the relevant email address:
					</p>
					
					<ul>
						<li>
							<p>
								To unsubscribe from this list send an e-mail to <br />
								<a href="mailto:log4net-dev-unsubscribe@logging.apache.org">log4net-dev-unsubscribe@logging.apache.org</a>.
							</p>
						</li>
							
						<li>
							<p>
								To unsubscribe from the digest list sent an e-mail to <br />
								<a href="mailto:log4net-dev-digest-unsubscribe@logging.apache.org">log4net-dev-digest-unsubscribe@logging.apache.org</a>.
							</p>
						</li>
					</ul>
				</section>

				<section id="mlist-posting" name="Posting">
					<p>
						Most of the guidelines for the log4net-user list also apply to the dev list.
						Please have a quick read through the <a href="support.html">guidelines</a>, thanks.
					</p>
					
					<p>
						<strong>To prevent spam, we require you to be subscribed to the list before posting to it.</strong>
					</p>
					
					<p>
						<em>This is the log4net developer list, it holds discussions relating to the
						development of log4net not the use of log4net. If you have a question that begins
						with the word "How" or you are unsure as the the appropriate list to post to then
						you probably want to start with the <a href="support.html">log4net-user list</a>.</em>
					</p>
					
					<p>
						Post to the list by sending mail to 
						<a href="mailto:log4net-dev@logging.apache.org">log4net-dev@logging.apache.org</a>.
					</p>
				</section>
			</section>

			<section id="svn" name="Source Access">
				<p>
					The source for log4net is held in the Apache Subversion source code control repository.
				</p>

				<section id="svn-view" name="Browsing SVN">
					<p>
						<a href="http://svn.apache.org/viewcvs.cgi/logging/log4net/">Browse log4net</a> 
						SVN repository using ViewCVS.
					</p>
				</section>

				<section id="svn-anon" name="Anonymous SVN Access">
					<p>
						Anyone can checkout source code from our anonymous SVN
						server. To do so, simply use the following command (if you are
						using a GUI SVN client, configure it appropriately).
					</p>
					
					<p>
						Checkout the logging/log4net module.
					</p>
					
					<source language="shell">
svn checkout http://svn.apache.org/repos/asf/logging/log4net/trunk log4net</source>

					<p>
						If you are not familiar with SVN, the Apache 
						<a href="http://www.apache.org/dev/version-control.html">Source Code Repositories</a> 
						page has links to more information on SVN.
					</p>
				</section>
			
			</section>
			
			<section id="jira" name="Issue Tracking">
				<p>
					Many bugs reported end up not being a bug in the log4net code, 
					but are due to incorrect configuration, problems caused by installed applications, 
					the operating system, etc.
				</p>
				<p>
					Before reporting a bug please make every effort to investigate and resolve the problem yourself. 
					Just reporting a bug will not fix it. A good bug report includes a detailed 
					description of the problem and a succinct test case which can reproduce the problem. 
				</p>
				<p>
					Before reporting an issue please investigate the following information sources for
					a potential resolution.
				</p>
				<ul>
					<li><a href="release/manual/introduction.html">Documentation</a></li>
					<li><a href="release/faq.html#internalDebug">Internal log4net debug</a></li>
					<li><a href="release/faq.html">FAQs</a></li>
					<li><a href="support.html">Mailing Lists</a></li>
				</ul>
				<p>
					Before reporting a bug, you are advised to discuss it on the relevant mailing list first.
				</p>
				<p>
					<a href="http://issues.apache.org/jira/browse/LOG4NET">Search the bug database</a> to see if the bug 
					you are seeing has already been reported. If it has been reported then you can vote for the issue.
				</p>
				
				<section id="jira-reporting" name="Reporting an Issue">
					<p>
						If after you have exhausted all other resources to resolve a problem you may want to file a bug report.
						Please make sure the problem is a bug in Logging and not a bug in your application.
					</p>
					<p>
						Please make sure you provide as much information as possible. Its very hard to fix a bug if the person 
						looking into the problem can't reproduce it. Here is a listing of information which should be included:
					</p>
					<ul>
						<li><b>Version</b> - log4net version, or if from a nightly build, version and date of build.</li>
						<li><b>Application Type</b> - Assembly type, i.e. exe or dll, and how your code is launched, e.g. console application, windows application, ASP.NET project, COM+ hosted object, etc...</li>
						<li><b>Framework</b> - The .NET framework running the application, name (e.g. MS .NET, Mono, SSCLI) and version.</li>
						<li><b>Platform</b> - Computer operating system, version, and hardware platform in use.</li>
						<li><b>Configuration</b> - Attach configuration files if they would help track down the bug.</li>
						<li><b>Log Files</b> - Review your logs files, produced with <a href="release/faq.html#internalDebug">internal log4net debug</a> enabled. Submit any relevant sections of the log which help document the bug.</li>
						<li><b>Stack Traces</b> - Any stack traces generated by the bug, if any.</li>
						<li><b>Example</b> - Example configuration files or web applications which demonstrate the bug. When submitting an example which reproduces the bug, please try to make it as simple as possible.</li>
						<li><b>Bug Fix Patch</b> - A patch created using <span class="code">diff -u</span> which fixes the bug. (If you have found a bug fix which can be applied to the code).</li>
						<li><b>Description of the Bug</b> - A description of the bug, include observed as well as expected behavior.</li>
						<li><b>Miscellaneous</b> - Any other information you feel will help track down the problem.</li>
					</ul>
					<p>
						<b>Just reporting a bug will not fix it. A good bug report includes a detailed description of the 
						problem and a succinct test case which can reproduce the problem.</b> The very best sort of report
						includes an NUnit testcase which reproduces the issue, this means that we can fix it and that we can
						be sure that it stays fixed in future!
					</p>
					<p>
						<a href="http://issues.apache.org/jira/browse/LOG4NET">Report a log4net issue here</a>. You will need to login to JIRA before you can submit an issue.
					</p>
				</section>
			</section>
			
			<section id="patch" name="Contributing Patches">
				<p>
					Before starting to work on a patch it is probably a good idea to join the log4net-dev
					mailing list to check that equivalent or complementary work is not already underway.
				</p>
				<p>
					Currently the only supported way of submitting patches to log4net
					is via the JIRA issue tracking system.
				</p>
				<p>
					The preferred method of generating a patch is a unified context diff against
					the latest development version in SVN. To do this you should do the following:
				</p>
				<ul>
					<li>
						<p>
							Get the latest version of the code from SVN, see the section above on 
							<i>Anonymous SVN Access</i> for details on how to obtain the SVN version. 
						</p>
					</li>
					<li>
						<p>
							Make your code changes to the log4net source. Please follow existing
							code styles where possible. If adding new API methods or classes then
							these should be appropriately documented with code comments.
							Contributions intended for inclusion in ASF products must be licensed 
							to ASF under the terms of the 
							<a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License</a>.
						</p>
					</li>
					<li>
						<p>
							Generate a unified context diff for the files you have changed. Run the
							<span class="code">svn diff &gt; patch-file</span> command from the root of the log4net
							codebase to generate a diff file. 
						</p>
					</li>
					<li>
						<p>
							If you have added new files these will not be included in the diff. You
							will need to attach these files separately.
						</p>
					</li>
				</ul>
				<p>
					If you are not using SVN then you can still generate a unified context diff
					using the <i>diff</i> GNU tool with the <i>-u</i> command line options. 
					The GNU tools are available for Windows as part
					of the <a href="www.cygwin.com">Cygwin</a> package.
				</p>
				<p>
					If you are unable to generate a diff please submit each file separately and place
					block comments around each code change to highlight the differences.
				</p>
				
				<p>
					In order to submit your patch please follow the following steps:
				</p>
				<ul>
					<li>
						<p>
							Create a new issue for your patch. On the 
							<a href="http://issues.apache.org/jira/browse/LOG4NET">log4net issues home page</a>
							select the <i>Create New Issue</i> from the menu bar. You will need to be logged
							into JIRA in order to create an issue.
						</p>
					</li>
					<li>
						<p>
							Select the issue type as appropriate.
						</p>
					</li>
					<li>
						<p>
							Prefix the summary with <b>[PATCH]</b>. Enter a description of the changes made,
							new features, or bug fixes in your patch.
						</p>
					</li>
					<li>
						<p>
							Once the issue has been created you can attach your patch file to the issue
							by selecting the <i>Attach file to this issue</i> operation from the left hand
							menu. When attaching your patch you must select the <b>Grant license to ASF for 
							inclusion in ASF works</b> option. When attaching a patch please include in the
							description the baseline version of log4net you used to build your patch, if against
							an SVN version please include the version number and if from a tag or branch include
							the repository path.
						</p>
					</li>
					<li>
						<p>
							If you have other files to attach, e.g. you have added new files to log4net, then
							attach each file separately. Please include in the description the name of the file
							attached and the path it should live in the project.
						</p>
					</li>
				</ul>
				<p>
					A notification will be sent to the log4net-dev list once you have created your issue,
					however it may also be worth mailing the log4net-dev list to encourage the project
					committers to apply your patch, or at least find out when they may do so.
				</p>
			</section>
			
<!-- TODO: Add guidelines for contributors
			<section id="guidelines" name="Guidelines for Contributors">
				<p>
					To contribute code to the log4net project follow the following
					guidelines:
				</p>
				
				<ul>
					<li>
						<p>
							TODO
						</p>
					</li>
				</ul>
			</section>
-->
		</section>
	</body>

</document>
